home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 9 / Night Owl CD-ROM (NOPV9) (Night Owl Publisher) (1993).ISO / 014a / orph154b.zip / MANUAL2.DOC < prev    next >
Text File  |  1993-05-07  |  102KB  |  2,703 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.                               Orpheus User's Guide
  12.  
  13.  
  14.                                   * Part II *
  15.  
  16.  
  17.  
  18.                           THE ORPHEUS COMMAND LANGUAGE
  19.  
  20.  
  21.  
  22.  
  23.  
  24.                         Copyright 1993 Hyperion Softword
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.                                        1
  60.  
  61.  
  62.  
  63.  
  64.   ---------------------------------------------------------------------------
  65.                         T A B L E  O F  C O N T E N T S
  66.   ---------------------------------------------------------------------------
  67.  
  68.  
  69.  
  70.  Chapter 1  -  Programming Hypertext ................................... 3
  71.     Init Cards ......................................................... 3
  72.     Action Cards ....................................................... 4
  73.     Graphic Cards ...................................................... 4
  74.     Orpheus Command Language ........................................... 5
  75.         Syntax ......................................................... 5
  76.         Flow Control ................................................... 6
  77.         Parameters ..................................................... 6
  78.         Variables ...................................................... 7
  79.     Testing Commands & Scripts ......................................... 7
  80.  
  81.  Chapter 2  -  Programming Command Reference ........................... 8
  82.     :[label] ........................................................... 8
  83.     Ansi ............................................................... 9
  84.     Gbox ............................................................... 9
  85.     Goto ............................................................... 11
  86.     Graphic ............................................................ 12
  87.     Gtext .............................................................. 14
  88.     Hide ............................................................... 16
  89.     Hotspot ............................................................ 17
  90.     If ................................................................. 20
  91.     Jump ............................................................... 21
  92.     Jumplist ........................................................... 23
  93.     Load ............................................................... 25
  94.     Lookfor ............................................................ 27
  95.     Netwk .............................................................. 27
  96.     Play ............................................................... 28
  97.     Quit ............................................................... 30
  98.     Run ................................................................ 31
  99.     Runbat ............................................................. 31
  100.     Set ................................................................ 32
  101.     Text ............................................................... 35
  102.     Trymode ............................................................ 39
  103.     Waitfor ............................................................ 40
  104.  
  105.  Chapter 3  -  Converting Old Commands ................................. 41
  106.     Versions Before 1.30: .............................................. 41
  107.        Graphic Commands ................................................ 41
  108.        Run Commands .................................................... 43
  109.        Random Commands ................................................. 43
  110.     Versions Before 1.50: .............................................. 44
  111.        Hotspot() ....................................................... 44
  112.        Jump(), Jumplist() .............................................. 44
  113.        Play() .......................................................... 44
  114.  
  115.  Table 1  -  Modes and Resolutions ..................................... 45
  116.  
  117.  
  118.  
  119.                                        2
  120.  
  121.  
  122.  
  123.  
  124.   ---------------------------------------------------------------------------
  125.                       CHAPTER 1  -  PROGRAMMING HYPERTEXT
  126.   ---------------------------------------------------------------------------
  127.  
  128.  
  129.  
  130.  Topics in this chapter:  Init Cards
  131.                           Action Cards
  132.                           Graphic Cards
  133.                           Orpheus Command Language
  134.                              Syntax
  135.                              Flow Control
  136.                              Parameters
  137.                              Variables
  138.                           Testing Commands & Scripts
  139.  
  140.  
  141.  
  142.         NOTE:  Users who are upgrading from a version of Orpheus prior to
  143.     1.50, and who have used the earlier commands to display graphics or play
  144.     music, will need to update their work to the new language standard.
  145.     Please see Chapter 3, "Converting Old Commands".
  146.  
  147.         If you wish to display graphics, play music, or launch external
  148.     programs, you will appreciate the power and flexibility of the Orpheus
  149.     Command Language.  First released with Version 1.30 of Orpheus, OCL
  150.     provides the ability to write anything from a one-line jump command to a
  151.     miniature program complete with hardware tests, multiple branches, timed
  152.     pauses, even a slide show.  Future releases will add more commands, with
  153.     the emphasis on multimedia and user interaction.
  154.  
  155.         There are three types of link that lead to programmable cards:  Init,
  156.     Action, and Graphic links.  Only these cards are programmable, and
  157.     whatever you write on them will be *performed* rather than being displayed
  158.     as text when your work is viewed with the Orpheus Reader.  Unlike normal
  159.     text cards, where only the top 24 or 25 lines will be seen in the Reader,
  160.     with programmable cards you can you use the entire workspace and be sure
  161.     that every line will be compiled into your finished work.
  162.  
  163.         In this chapter we will explore the uses, syntax, and vocabulary of
  164.     the Orpheus Command Language.  In the next chapter you will find a
  165.     thorough presentation of every command, together with extensive examples.
  166.  
  167.  
  168.  Init Cards
  169.  
  170.         Inits are created by opening the Link Menu while in any text card
  171.     and selecting "Init".  Only text cards can have Inits, and they may have
  172.     only one each.  (Text cards include the Homecard and all cards attached
  173.     to Door, Note, or More links.)  When you are in a card that has an Init,
  174.     you can jump to it (in OH.EXE) either by pressing <Alt-I> or by opening
  175.     the Link Menu and selecting "Edit Init".
  176.  
  177.  
  178.  
  179.                                        3
  180.  
  181.  
  182.  
  183.  
  184.         When the Orpheus Reader loads a card that has an Init, it loads the
  185.     Init in the background and performs its commands before displaying the
  186.     Init's parent.  For example, an Init off the Homecard might contain a
  187.     graphical book-cover:  commands to display one or more graphics, or even a
  188.     choice of graphics or ansi graphics depending on the user's hardware.
  189.     Inits are processed every time the user enters a card that has one -- with
  190.     the sole exception of the Homecard, whose Init (if any) is only processed
  191.     once.
  192.  
  193.         After the last command in an Init, control returns to its parent;
  194.     normally this means that the text card is displayed and the user regains
  195.     the ability to navigate.  The exception is when the last command processed
  196.     is a jump() command, i.e. an instruction to go to a different card.  In
  197.     that case the Reader loads the new card and displays that, unless it too
  198.     has an Init that must be processed first.
  199.  
  200.         Aside from enabling you to do opening sequences, Inits are good places
  201.     to set variables and declare data automatically.  (These aspects will
  202.     expand considerably as the language evolves.)  Inits cannot contain links
  203.     to other cards, nor can a graphic displayed from an Init contain hotspots.
  204.  
  205.  
  206.  Action Cards
  207.  
  208.         Action cards are created by opening an Action link on a word or phrase
  209.     in any text card.  In OH.EXE you can jump to an Action card the same as
  210.     you would to any card that is accessed through a linkword.
  211.  
  212.         In the Orpheus Reader, when the user clicks on an Action linkword the
  213.     Action card is loaded in the background and its commands are processed.
  214.     After the last command, control returns immediately to the parent card. If
  215.     a graphic or ansi graphic was displayed, or if an external program was
  216.     launched, the parent card is displayed afresh.  The exception is if the
  217.     last command processed is a jump() command, i.e. an instruction to go to a
  218.     different card.  In that case the Reader loads and displays the new card.
  219.  
  220.         Action cards cannot contain links to other cards, nor can a graphic
  221.     displayed from an Action card contain hotspots.
  222.  
  223.  
  224.  Graphic Cards
  225.  
  226.         Graphic cards are created by opening a Graphic link on a word or
  227.     phrase in any text card.  You can jump to a Graphic card the same as you
  228.     would to any card that is accessed through a linkword.  When you do so in
  229.     OH.EXE you go to the Graphic card itself, not to whatever you intend to
  230.     display with it.  But when you jump to a Graphic in the Orpheus Reader you
  231.     really do jump to what is intended for display.
  232.  
  233.         Like an Init or Action card, a Graphic card may contain anything from
  234.     a single command to a script of tests and branches that display a suitable
  235.     graphic or ansi graphic depending on the capabilities of the user's
  236.  
  237.  
  238.  
  239.                                        4
  240.  
  241.  
  242.  
  243.  
  244.     hardware.  A Graphic card may even contain a sequence of multiple graphics
  245.     separated by timed delays.  Unlike Init and Action cards, when the last
  246.     command on a Graphic card is processed in the Reader, assuming that a
  247.     graphic or ansi graphic is onscreen, control remains in the Graphic card
  248.     the same as it would in a text card.  That is, a pointer appears, the
  249.     user can open the menu or use the titlebar, and if the graphic has
  250.     hotspots he can navigate through them.
  251.  
  252.         If you have selected "Graphic Titlebar" on the Project Menu, the
  253.     Orpheus Reader's titlebar will appear automatically atop the last graphic
  254.     or ansi graphic displayed from a Graphic card.  If this option was not
  255.     selected, the titlebar only appears when the user moves the mouse pointer
  256.     to the top of the screen (or presses Esc if no mouse is installed).
  257.  
  258.         Graphic cards may contain hotspots with links to other graphics or to
  259.     text cards, with just one restriction:  the linkword in a hotspot() 
  260.     command may receive a Door link or a Graphic link, but no other kind.
  261.     Graphic cards may not have Inits or More links.  A jump() command in a
  262.     Graphic card will either be rejected by the compiler or ignored by the
  263.     Reader.
  264.  
  265.         If by the last command in a Graphic card a graphic or ansi graphic is
  266.     NOT onscreen, the Orpheus Reader assumes that an error has occurred and
  267.     returns automatically to the parent card.
  268.  
  269.  
  270.  Orpheus Command Language
  271.  
  272.         If you have ever written a batch file or used any other programming
  273.     language, you will soon recognize how to get things done in Orpheus
  274.     Command Language.  Even if you have never programmed at all, you will find
  275.     it easy to accomplish what you need by using the examples given in the
  276.     next chapter.
  277.  
  278.     SYNTAX
  279.     Here are the basic rules of OCL:
  280.  
  281.         * Command lines:  commands must begin at the leftmost column.  The
  282.           examples in this manual are indented to enhance readability; in
  283.           Orpheus they would be ignored unless moved to the left of the
  284.           screen.
  285.  
  286.         * Comment lines:  lines beginning with a "/" or ";" are considered
  287.           to be comment lines and are ignored by the command processor (and
  288.           the compiler).  Additionally, lines beginning with a space are
  289.           ignored unless they are carried-over data from a preceding command.
  290.  
  291.         * Commands may be entered in any combination of upper and lower case.
  292.           To enhance readability, the examples in this manual use lowercase
  293.           for commands and uppercase for labels, but you do not have to do
  294.           the same.  (Music strings however must be in uppercase.)
  295.  
  296.  
  297.  
  298.  
  299.                                        5
  300.  
  301.  
  302.  
  303.  
  304.         * Within a command line, spaces may be used for readability, but are
  305.           not required.  The two examples below are equally valid:
  306.  
  307.                 set(fadein=tunnelin,fadeout=venetian,delay=1)
  308.                 set ( fadein = tunnelin, fadeout = venetian, delay = 1 )
  309.  
  310.  
  311.     FLOW CONTROL
  312.     The sum of the commands in a programmable card is called a "script".
  313.     Sometimes a script may consist of a single command, such as "jump
  314.     (retrace)" in an Action card to return the reader to wherever he came
  315.     from.  More often however you will write a sequence of commands that may
  316.     include various possible things that you would like to happen depending on
  317.     circumstances.  The following example displays one of 3 possible screens
  318.     in a Graphic card; which screen is chosen depends on whether the user has
  319.     a VGA display, an EGA display, or neither.
  320.  
  321.         trymode (19)                     // 1: Can we do VGA mode 19?
  322.         if (failed) goto NEXT            // 2: If not go to line 5.
  323.         graphic (vga_pic.pcx, 19, full)  // 3: Show fullscreen VGA graphic.
  324.         goto END                         // 4: Go to line 12.
  325.         :NEXT                            // 5: Label for goto command.
  326.         trymode (16)                     // 6: Can we do EGA mode 16?
  327.         if (failed) goto TEXT            // 7: If not go to line 10.
  328.         graphic (ega_pic.pcx, 16, full)  // 8: Show fullscreen EGA graphic.
  329.         goto END                         // 9: Go to line 12.
  330.         :TEXT                            // 10: Label for goto command.
  331.         ansi (ansi_pic.ans)              // 11: Show an ansi graphic.
  332.         :END                             // 12: Label for goto command
  333.  
  334.     This script uses two "if()" tests, three labels (":NEXT", ":TEXT", and
  335.     ":END"), and four "goto" commands.  Processing flows along one of three
  336.     possible paths depending on the user's hardware, with the result that in
  337.     just 12 simple lines we can ensure that if the user clicks on a certain
  338.     Graphic linkword he will actually see something.  The next chapter tells
  339.     about other conditions you can test, and gives a full explanation of how
  340.     to use each of the commands illustrated here.
  341.  
  342.     PARAMETERS
  343.     With the sole exception of "goto", all OCL commands must be followed by
  344.     parentheses, which usually enclose one or more parameters.  The number and
  345.     order of parameters are specific to each command, so before you use a
  346.     command for the first time you should read its entry in the Programming
  347.     Command Reference (Chapter 2).  In the following example, trymode() takes
  348.     a numeric parameter, if() takes a symbolic parameter (a keyword),
  349.     text() takes a string parameter, and quit() takes no parameter.
  350.  
  351.         trymode (16)                     // 1: Can we do EGA mode 16?
  352.         if (okay) goto END               // 2: If so, go to line 5.
  353.         text ("This book requires EGA graphics")  // 3: Text box.
  354.         quit ()                          // 4: Exit the Orpheus Reader.
  355.         :END                             // 5: Label for goto.
  356.  
  357.  
  358.  
  359.                                        6
  360.  
  361.  
  362.  
  363.  
  364.     (This script is one that would go in an Init off the Homecard, in a book
  365.     with a large number of EGA graphics at critical locations.  If the user
  366.     has an EGA-capable display he will proceed without even knowing that this
  367.     script was processed.  If he has a CGA or monochrome display, he will see
  368.     a note box with the message in it, and when he presses a key the
  369.     program will harmlessly exit.)
  370.  
  371.     VARIABLES
  372.     Variables are objects in memory that can hold values or other data.
  373.     Sometimes values are indicated with numbers, and sometimes they are
  374.     indicated symbolically using keywords.  The trymode() command sets an
  375.     internal variable to either "failed" or "okay" depending on whether the
  376.     user's display can or cannot switch to the specified video mode.  These
  377.     are symbolic values; in this case, the variable is unnamed.  Most
  378.     variables however do have names, and the set() command lets us assign
  379.     values to them, either with a number or with a keyword.
  380.  
  381.                 set (fadein=venetian, fadeout=venetian, delay=1)
  382.  
  383.     In this example, the first two variables are assigned the same symbolic
  384.     value, "venetian", which refers to a style of fading a graphic on or off
  385.     the screen.  The third variable is assigned a number representing the
  386.     delay factor for this effect; if delay=0 the fade is rather fast, while if
  387.     delay=3 the fade is rather slow.
  388.  
  389.  
  390.  Testing Commands & Scripts
  391.  
  392.         Most commands can be performed within OH.EXE as they would be in the
  393.     Orpheus Reader.  Those that cannot are at least checked for errors, and a
  394.     report given accordingly.  To test an individual command line, place the
  395.     cursor on that line (or on the line where it begins) and press <Alt-G>.  
  396.     This is an easy way to see if you are specifying the right video mode for 
  397.     a graphic() command, or to hear a performance of a music string.  In the 
  398.     case of a graphic() or ansi() command, once the image is displayed you 
  399.     need only press a key to return to editing.
  400.  
  401.         To test a complete script -- the entire sequence of commands in a
  402.     programmable card -- press <Alt-C> while in that card.  This is the "Check
  403.     Card" command, which works quite differently when given from a normal text
  404.     card.  Additionally, if you use <Alt-C> from an Action or Init card and 
  405.     your script includes a command to display a graphic or ansi graphic, you
  406.     will notice that without a waitfor() command at the end your graphic 
  407.     merely flashes onscreen and then disappears as the Edit window returns.  
  408.     This is because, as I explained above, when the last command is processed 
  409.     in an Action or Init card control returns immediately to the parent card.
  410.  
  411.         In a Graphic card (which does NOT require a waitfor() line at the
  412.     end), pressing <Alt-C> gives you the additional ability to create
  413.     hotspots.  This is explained under the hotspot() entry in the next
  414.     chapter.
  415.  
  416.  
  417.  
  418.  
  419.                                        7
  420.  
  421.  
  422.  
  423.  
  424.   ---------------------------------------------------------------------------
  425.                   CHAPTER 2  -  PROGRAMMING COMMAND REFERENCE
  426.   ---------------------------------------------------------------------------
  427.  
  428.  
  429.  
  430.  Commands in this reference:  :[label]           Load
  431.                               Ansi               Lookfor
  432.                               Gbox               Netwk
  433.                               Goto               Play
  434.                               Graphic            Quit
  435.                               Gtext              Run
  436.                               Hide               Runbat
  437.                               Hotspot            Set
  438.                               If                 Text
  439.                               Jump               Trymode
  440.                               Jumplist           Waitfor
  441.  
  442.  
  443.  
  444.         This chapter provides extensive discussion of every command in the
  445.     Orpheus Command Language.  For a general introduction to programming in
  446.     Orpheus, see Chapter 1.
  447.  
  448.  
  449.  :[label]
  450.  
  451.         Lines beginning with ":" are considered label lines, with the word
  452.     immediately following being a label for use in flow control.  As in DOS
  453.     batch files, labels are used with the goto command to control the flow
  454.     of processing.  The following example checks for a monochrome display,
  455.     and if one is detected directs processing to the ":END" label, which in
  456.     this case is the end of the script.  If a mono display is not detected,
  457.     processing continues to the next lines, which display a graphic and then
  458.     wait for the user to press a key.
  459.  
  460.                 if (mono) goto END
  461.                 graphic(mypic.pcx, 5, full)
  462.                 waitfor()
  463.                 :END
  464.  
  465.     Labels can be whatever you wish, but to avoid confusion you should
  466.     avoid using commands or keywords belonging to Orpheus Command Language.
  467.     A label is a single word, or multiple words joined by hyphen or
  468.     underscore, such as "first-part" or "has_vga".  (By the way, in case
  469.     you are wondering:  the label ":END" has no special meaning to
  470.     Orpheus.  You could use ":grmpflstx" and it would have the same effect,
  471.     as long as your goto command was "goto grmpflstx".  Also, if you
  472.     were to place the label ":END" in the middle of the script that would
  473.     =NOT= make it the end of the script.)
  474.  
  475.  
  476.  
  477.  
  478.  
  479.                                        8
  480.  
  481.  
  482.  
  483.  
  484.  Ansi()
  485.  
  486.         Display a text file containing ANSI escape sequences for color
  487.     effects.  Takes a single parameter, the name of the file to display.
  488.  
  489.                 ansi(ansi_pic.ans)
  490.  
  491.     Ansi files may be located in either of two locations, depending on whether
  492.     OH.EXE or the Orpheus Reader is looking for them.  OH.EXE looks first
  493.     in the current directory, the one containing the Homecard.  The Reader
  494.     looks first in whichever directory contains the rest of the book files
  495.     (normally the current directory unless specified on the command line).
  496.     If the ansi file is not found there, Orpheus then checks for an ORPHEUS
  497.     environment variable, and if one exists uses the directory specified
  498.     there.  (See Appendix C, "Using the ORPHEUS Environment Variable".)
  499.  
  500.  
  501.  Gbox()
  502.  
  503.         Draw a filled rectangle in the current graphic video mode.  Requires
  504.     that a graphic video mode be already in effect on the user's display,
  505.     either as the result of a graphic() call or by using set() with the "mode"
  506.     keyword.  Parameters:  optional use of the keyword "text", and 5 numeric
  507.     parameters to specify the color, coordinates, and size of the rectangle.
  508.     Gbox() cannot be used in text modes.
  509.  
  510.     COLOR
  511.     The first numeric parameter sets the color for the rectangle.  Check the
  512.     table of Modes & Resolutions for the number of colors available in each
  513.     video mode.  Since some PCX files reset the color palettes, you may get
  514.     different results using the same number in the same mode but in
  515.     association with different PCX files.
  516.  
  517.     COORDINATES
  518.     The second numerical parameter gives the column of the upper left corner
  519.     of the box, with 0 as the left edge of the screen.  The next parameter
  520.     gives the row of the upper left corner, with 0 as the top of the screen.
  521.     The next parameter gives the width of the box (from left to right), and
  522.     the last gives its height (from top to bottom).  The smallest number
  523.     permitted for the height and width is 1, which has the effect of drawing
  524.     a thin line.
  525.  
  526.     COORDINATE SYSTEMS - PIXELS OR CELLS
  527.     Coordinates may be given in either character cells or pixel counts.  As
  528.     shown in the table of Modes & Resolutions, mode 16 (for example) has a
  529.     resolution of 640x350, with 80x25 character cells.  In other words, the
  530.     screen in mode 16 has 640 pixels across by 350 pixels down, or 80 standard
  531.     characters across by 25 standard characters down.  While counting in
  532.     pixels gives you more precision, in some situations you will find it more
  533.     convenient to count in character cells.  If you use the keyword "text" as
  534.     the first parameter, all coordinates are read as character cells.  If you
  535.     do NOT use the keyword "text", coordinates are read as pixel counts.
  536.  
  537.  
  538.  
  539.                                        9
  540.  
  541.  
  542.  
  543.  
  544.                 set(mode = 16)
  545.                 gbox(text, 14, 9, 3, 61, 20)
  546.                 gbox(text, 1, 12, 4, 55, 18)
  547.                 gbox(15, 99, 58, 427, 235)
  548.  
  549.     This example puts up an attractive white box framed with a narrow
  550.     blue border surrounded in turn by a wide yellow border.  In actuality
  551.     there are 3 boxes created, one on top of the other.  The first gbox()
  552.     command draws the large yellow box (color 14), using text coordinates.
  553.     The second gbox() command draws a smaller blue box (color 1) inside it,
  554.     again using text coordinates.  Notice that the upper left corner of the
  555.     yellow box is at column 9, row 3, while the upper left corner of the
  556.     blue box is at column 12, row 4 -- below and to the right.  Additionally,
  557.     while the yellow box is 61 columns wide and 20 rows deep, the blue box
  558.     is 55 columns wide and 18 rows deep, so it fits neatly inside.  For the
  559.     white box (color 15) we want finer control in order to ensure that only
  560.     a thin border from the blue box is left showing.  By NOT using the text
  561.     keyword we ensure that our coordinate parameters are read as pixels.  With
  562.     a little experimentation we can get the desired effect, just by trying
  563.     some approximate numbers, pressing Alt-C to check the results, and making
  564.     adjustments accordingly.  In this case the blue box is reduced to a border
  565.     of 2 or 3 pixels all around.
  566.  
  567.         By specifying a depth or width of 1 or 2 pixels, gbox() can also
  568.     be used to draw a horizontal or vertical line.  You can in fact build up
  569.     some very interesting displays, generally with better performance and
  570.     less disk-space than if you created them in a paint program and saved
  571.     them to a PCX file.  Note however that if you wish to use gbox() and
  572.     then call graphic() to combine an image with a design onscreen, you
  573.     must use the command "set(fadein = off, fadeout = off)" to prevent
  574.     Orpheus from erasing the screen before displaying the graphic.
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.                                       10
  600.  
  601.  
  602.  
  603.  
  604.  Goto
  605.  
  606.         Direct command processing to the label following the goto command.
  607.     Goto may be used in two circumstances:  on the same line as an if() test,
  608.     and on a line of its own.
  609.  
  610.                 trymode(18)
  611.                 if (failed) goto DO_ANSI
  612.                 graphic(big_pic.pcx, 18, full)
  613.                 goto END
  614.                 :DO_ANSI
  615.                 ansi(ansipic.ans)
  616.                 :END
  617.  
  618.     This example checks whether the user's display can switch to mode 18,
  619.     a VGA mode.  If it can't, the first goto directs the flow to the :DO_ANSI
  620.     label.  If it can, a graphic is displayed and then the second goto
  621.     directs the flow to the :END label.  Note that goto can direct the flow
  622.     to *any* label in the script, regardless of whether the line is above
  623.     or below the goto.
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.                                       11
  660.  
  661.  
  662.  
  663.  
  664.  Graphic()
  665.  
  666.         Display a graphic in one of the image file formats permitted in
  667.     Orpheus.  Parameters:  three for a full-screen graphic, otherwise from
  668.     three to five.  The first parameter is the filename, the second is the
  669.     video mode in which to display it.  If the third parameter is the keyword
  670.     "full", no further parameters are required.  If the third parameter is not
  671.     "full", the third and fourth parameters give the x-y coordinates (column-
  672.     row in pixels) of the origin of the image, while the fifth (required for
  673.     SPR/PPR files only) gives the image width in pixels.
  674.  
  675.         In the following examples, an identical full-screen graphic is shown
  676.     in both PCX and SPR image file formats, using mode 13, which has a
  677.     resolution of 320 columns by 200 rows:
  678.  
  679.                 graphic(example1.pcx, 13, full)
  680.                 graphic(example2.pcx, 13, 0, 0)
  681.                 graphic(example3.spr, 13, full)
  682.                 graphic(example4.spr, 13, 0, 199, 320)
  683.  
  684.  
  685.     PCX FILES
  686.  
  687.         With PCX files an image is considered to originate at the upper left
  688.     corner.  With a full-screen graphic this would be column 0, row 0, as
  689.     shown in example 2 above.  We do not require the image width of a PCX
  690.     file, so there is no fifth parameter.
  691.  
  692.         Let's suppose we have a PCX graphic that is half the size of the
  693.     screen in each dimension.  Since our examples use mode 13 with a
  694.     resolution of 320 x 200, we'll say that our image is 160 pixels across
  695.     by 100 pixels down.  To center this image we would use the following:
  696.  
  697.                 graphic(example5.pcx, 79, 49)
  698.  
  699.     Where did these numbers come from?  We take the horizontal resolution,
  700.     subtract the width of the image, divide by two, then subtract one:
  701.     320-160=160; 160/2=80; 80-1=79.  We subtract 1 because screen coordinates
  702.     are always counted from 0; thus the leftmost pixel coordinate is 0 and
  703.     the rightmost pixel coordinate (in mode 13) is 319.  The same procedure
  704.     works for the vertical dimension.  Take the vertical resolution, subtract
  705.     the height of the image, divide by two, subtract one:  200-100=100;
  706.     100/2=50; 50-1=49.
  707.  
  708.         You won't always know the dimensions of an image nor where you want to
  709.     show it onscreen.  The best way to proceed is to try out different numbers
  710.     and use the <Alt-G> Go Command to view the results.
  711.  
  712.     SPR/PPR FILES
  713.  
  714.         SPR files are captured using the SNAPSHOT utility, which comes with
  715.     the registered version of Orpheus.  PPR files are generated from SPR
  716.  
  717.  
  718.  
  719.                                       12
  720.  
  721.  
  722.  
  723.  
  724.     files using a Fastgraph utility that compresses them.  With SPR and PPR
  725.     files, an image is considered to originate at the LOWER left corner,
  726.     whereas with PCX files it originates at the upper left.  In addition,
  727.     SPR/PPR files require that we give the image width.  This accounts for
  728.     the numbers in example 4:
  729.  
  730.                 graphic(example4.spr, 13, 0, 199, 320)
  731.  
  732.     Since this a full-screen graphic and the resolution is 320 x 200, the
  733.     horizontal component of the lower left corner is pixel column 0, but the
  734.     vertical component is 199 -- 1 less than the vertical resolution.  The
  735.     width of the image is of course 320 pixels.
  736.  
  737.         Let's suppose we have an SPR graphic that is half the size of the
  738.     screen in both dimensions, in other words 160 pixels across by 100 pixels
  739.     down.  We'll center it just like we did with the half-size PCX graphic
  740.     above.  To calculate the column coordinate we follow the same procedure:
  741.     horizontal resolution - width, divided by 2, minus 1, or: 320-160=160;
  742.     160/2=80; 80-1=79.  For the row coordinate however we must proceed
  743.     differently because we're calculating the lower left corner rather than
  744.     the upper left corner.  The procedure is:  vertical resolution - height,
  745.     divided by 2, subtract that from the vertical resolution, minus 1, or:
  746.     200-100=100; 100/2=50; 200-50=150; 150-1=149.  Our command to center the
  747.     image would thus be:
  748.  
  749.                 graphic(example6.spr, 13, 79, 149, 160)
  750.  
  751.         Unless you stick to a single file type and a single video mode, you
  752.     will find it useful to consult a chart of the video modes and their
  753.     screen resolutions.  You can find such a chart in online help, under
  754.     Programming Hypertext->Graphics->Modes & Resolutions.
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.                                       13
  780.  
  781.  
  782.  
  783.  
  784.  Gtext()
  785.  
  786.         Display text in the current graphic video mode.  Requires that a
  787.     graphic video mode be already in effect on the user's display, either as
  788.     the result of a graphic() call or by using set() with the "mode" keyword.
  789.     Parameters:  optional use of the keyword "text", 3 numeric parameters
  790.     giving the foreground color of the text and the coordinates at which to
  791.     display the first character, and one or more text strings enclosed in
  792.     quotation marks.
  793.  
  794.     FONTS
  795.     Bitmapped fonts are not yet available (but soon will be); in their place
  796.     Orpheus displays the standard "system" characters that are built into
  797.     ROM.
  798.  
  799.     COLOR
  800.     The first numerical parameter gives the foreground color in which text
  801.     will be displayed.  For the most readable text you will often want to
  802.     create a consistent background color by preceding the gtext() call with
  803.     one to gbox().  Check the table of Modes & Resolutions for the number of
  804.     colors available in each video mode.  Since some PCX files reset the color
  805.     palettes, you may get different results if you display text on a PCX
  806.     graphic.
  807.  
  808.     COORDINATES
  809.     The second numerical parameter gives the column at which the first
  810.     character of the first string will be displayed, with 0 as the left edge
  811.     of the screen.  The next parameter gives the row, with 0 as the top of the
  812.     screen.  Multiple strings are left-justified with the first character
  813.     of the first string, and are displayed further down the screen according
  814.     to the calculated height of a character cell.
  815.  
  816.     COORDINATE SYSTEMS - PIXELS OR CELLS
  817.     Coordinates may be given in either character cells or pixel counts.  As
  818.     shown in the table of Modes & Resolutions, mode 16 for example has a
  819.     resolution of 640x350, with 80x25 character cells.  In other words, the
  820.     screen in mode 16 has 640 pixels across by 350 pixels down, or 80 standard
  821.     characters across by 25 standard characters down.  While counting in
  822.     pixels gives you far more precision, in some situations you will find it
  823.     more convenient to count in character cells.  If you use the keyword
  824.     "text" as the first parameter, all coordinates will be read as character
  825.     cells.  If you do NOT use the keyword "text", coordinates will be read
  826.     as pixel counts.
  827.  
  828.         In the current version of Orpheus, since only ROM characters are
  829.     supported (and they can ONLY be displayed along cell coordinates),
  830.     even if you give pixel coordinates they will be converted to cell
  831.     coordinates.  When bit-mapped fonts are available you will be able
  832.     to use pixel coordinates for finer positioning.
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.                                       14
  840.  
  841.  
  842.  
  843.  
  844.         The following illustration continues from the example begun for
  845.     gbox().
  846.  
  847.                 set(fadein = off, fadeout = off, mode = 16)
  848.                 gbox(text, 14, 9, 3, 61, 20)        // yellow box
  849.                 gbox(text, 1, 12, 4, 55, 18)        // blue box inside it
  850.                 gbox(15, 99, 58, 427, 234)          // white box inside it
  851.                 gbox(11, 99, 287, 427, 6)           // bright cyan lines
  852.                 gbox(11, 117, 278, 391, 5)
  853.                 gbox(11, 135, 271, 355, 4)
  854.                 gbox(11, 153, 266, 319, 3)
  855.                 gbox(11, 170, 262, 285, 2)
  856.                 gbox(11, 185, 259, 255, 1)
  857.                 gtext(text, 5, 28, 8, "Greetings", " ", "from", " ",
  858.                     "Rod Willmot and the animals", " ",
  859.                     "at Hyperion Softword!")
  860.                 gtext(text, 5, 32, 17, "1-819-566-6296")
  861.                 set(fadeout = normal)
  862.  
  863.     This example begins by turning off fades in case we decide to add an
  864.     on-disk image using graphic().  It then sets the video mode in preparation
  865.     for the calls to gbox() and gtext().  The first three gbox() commands
  866.     are taken from the example given above to illustrated gbox(); they set
  867.     up a large white box in the middle of the screen, nicely framed by
  868.     a thin blue border and a wider yellow border.  The next 6 commands
  869.     draw a series of lines of decreasing thickness, from the bottom of the
  870.     white box toward the center; the effect is of receding perspective.
  871.     Finally we come to the gtext() commands, both of which use the "text"
  872.     keyword to let us use the coarser but easier cell coordinates.  The
  873.     color used is 5, magenta.  The first set of strings starts at column
  874.     28, row 5; blank lines are created by entering a string as " ", a
  875.     single space.  Each additional string within the same command is
  876.     left-justified with the first string, which begins exactly at the
  877.     specified coordinates.
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.                                       15
  900.  
  901.  
  902.  
  903.  
  904.  Hide()
  905.  
  906.         The hide() command is for use in an Init card when you wish to conceal
  907.     links in its parent card.  The command can be given either with no
  908.     parameters or with an indeterminate sequence of numeric parameters.
  909.  
  910.                 hide()
  911.                 hide(0, 2, 5)
  912.  
  913.     In the first example, ALL links in the parent card are concealed:  if it
  914.     has a More link this fact will not be known by the reader, and if it has
  915.     any linkwords they will look like ordinary text -- and clicking on them
  916.     will have no effect.  In the second example, the More link and the second
  917.     and fifth linkwords are concealed.  To sum up:  using hide() with no
  918.     parameters hides all links in the parent.  Using "0" as a parameter hides
  919.     the More link; other numbers hide the equivalent linkwords as numbered
  920.     sequentially from top to bottom and from left to right down the screen.
  921.  
  922.         The hide() command could be used in a network environment where not
  923.     all readers should have access to branches with sensitive material.  In
  924.     a work with illustrations in VGA color, it could be used to prevent
  925.     users with mono displays from experiencing the frustration of clicking
  926.     on Graphic links and getting no response.  Hide() will also add to the
  927.     repertoire of effects when the Orpheus Command Language extends to
  928.     interactive dialogs and author-created variables.
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.                                       16
  960.  
  961.  
  962.  
  963.  
  964.  Hotspot()
  965.  
  966.         The hotspot() command defines an area of a graphic or ansi screen that
  967.     is linked to another graphic or text card, much like a linkword in a text
  968.     card.  Hotspots may only be created in Graphic cards, where they can be
  969.     associated either with true graphics (displayed in a graphic video mode)
  970.     or with ansi graphics (displayed in text mode).  The hotspot() command
  971.     cannot be used in Action or Init cards.  Hotspot data created for a true
  972.     graphic is NOT compatible with data created for an ansi graphic.
  973.  
  974.         There are two parameters:  a linkword, and a coded data string
  975.     enclosed in quotation marks.  The first character of the string is "0"
  976.     if the hotspot is for a true graphic, "1" if it is for an ansi graphic.
  977.  
  978.                 hotspot( linkword , "0NLGOKLPKWQKXRKVSKUT\C")
  979.  
  980.         The hotspot() command, including the coded data string, is entered
  981.     by Orpheus rather than being typed in by you.  The procedure is as
  982.     follows:  assuming you are in a Graphic card with a valid graphic() or
  983.     ansi() command, place the cursor on an empty line.  Press <Alt-C> to
  984.     perform the entire script, even if it consists only of one graphic() or
  985.     ansi() command.  Orpheus displays the graphic and waits for your input.
  986.     Press <H> to indicate that you wish to make a hotspot; Orpheus will beep
  987.     twice in acknowledgement.  You can now draw the hotspot by pressing or
  988.     clicking the left mouse button.  To erase an area, press or click the
  989.     right mouse button.  (Neither drawing nor erasing actually alters your
  990.     original hotspot.)  To cancel a partially-drawn hotspot and refresh the
  991.     screen, press <Esc>.  To signal that you have finished the hotspot, press
  992.     <Enter>.
  993.  
  994.         When you press <Enter> to finish a hotspot, Orpheus returns you to
  995.     the Graphic card where you will now see the new hotspot() command,
  996.     something like this (the # will be 0 for a true graphic, 1 for an ansi
  997.     screen):
  998.  
  999.                 hotspot( linkword , "#.......data string.........")
  1000.  
  1001.     One final step is required to make the command complete:  using either
  1002.     the word "linkword" or a word of your own to replace it, open a link on
  1003.     that word (the first parameter in the hotspot() command) to create a new
  1004.     linked card.  Two link types are permitted:  Door links and Graphic links.
  1005.     Until this step is done the command is not considered complete and Orpheus
  1006.     will not carry out an <Alt-C> command in that card.  When it is complete,
  1007.     press <Alt-C> and move the mouse pointer over the area where you drew the
  1008.     hotspot; notice that the mouse pointer changes shape.
  1009.  
  1010.         A hotspot can be small and simple, or large and complex; it can even
  1011.     be scattered in several unconnected locations.  The size and complexity
  1012.     of the hotspot determines the length of the data string forming the
  1013.     second parameter.  If the data string is too long to fit on one line,
  1014.     Orpheus will carry it over onto one or more subsequent lines.  As in all
  1015.     cases where data is carried over, each additional line must be padded
  1016.  
  1017.  
  1018.  
  1019.                                       17
  1020.  
  1021.  
  1022.  
  1023.  
  1024.     with one or more leading spaces.  (Orpheus does this automatically, but
  1025.     you should know the rule in case you rearrange things manually.)
  1026.  
  1027.         A graphic may have as many hotspots as you can define within the
  1028.     50-line workspace of a card.  Additionally, just as you can use flow
  1029.     control to provide alternate graphics for different hardware, you can
  1030.     provide a different set of hotspots for each graphic -- or use the same
  1031.     hotspots for all of them.  In the first example below, we put up either
  1032.     a VGA or an EGA graphic, using modes that have a resolution of 320 x 200.
  1033.     We then install 2 hotspots which are applicable to both.
  1034.  
  1035.                 trymode(19)
  1036.                 if (failed) goto HAS_EGA
  1037.                 graphic(vga_pic.pcx, 19, full)
  1038.                 goto ADD_HOTSPOTS
  1039.                 :HAS_EGA
  1040.                 graphic(ega_pic.pcx, 13, full)
  1041.                 :ADD_HOTSPOTS
  1042.                 hotspot( link1 , "0.........data string.........")
  1043.                 hotspot( link2 , "0.........data string.........")
  1044.  
  1045.         In the next example we will again use a VGA and an EGA graphic, but
  1046.     one will use a resolution of 320 x 400 (mode 23), while the other will
  1047.     use a resolution of 640 x 350 (mode 16).  We'll suppose that the pictures
  1048.     are sufficiently different that each requires its own set of hotspots.
  1049.     (For safety's sake, you should never try to use a hotspot in two different
  1050.     video modes.)  In order to create the hotspots we must of course press
  1051.     <Alt-C> to perform the entire script; this means that at some point we
  1052.     must comment out all command lines that do not pertain to the graphic for
  1053.     which we wish to create a hotspot.
  1054.  
  1055.                 /trymode(23)
  1056.                 /if (failed) goto HAS_EGA
  1057.                 /graphic(vga_pic.pcx, 23, full)
  1058.                 /hotspot( link1 , "0.........data string.........")
  1059.                 /hotspot( link2 , "0.........data string.........")
  1060.                 /goto END
  1061.                 /:HAS_EGA
  1062.                 graphic(ega_pic.pcx, 16, full)
  1063.                 hotspot( link1 , "0.........data string.........")
  1064.                 :END
  1065.  
  1066.     In this example we have already completed our work for the VGA graphic,
  1067.     and have temporarily commented out that section of the script using
  1068.     a "/" character at the beginning of each line.  This ensures that <Alt-C>
  1069.     will only display the EGA graphic.  The example shows one hotspot
  1070.     completed, with an empty line left where we can create another. When work
  1071.     is completed for both graphics we simply remove the comment characters to
  1072.     return the commented-out lines to the script.  To provide ansi graphics
  1073.     for users with neither EGA nor VGA, we would comment out all of the
  1074.     commands that use graphic modes, add our ansi() command to display an ansi
  1075.     screen, then proceed as above to create hotspots in the ansi screen.
  1076.  
  1077.  
  1078.  
  1079.                                       18
  1080.  
  1081.  
  1082.  
  1083.  
  1084.     MULTIPLE COPIES OF LINKWORDS
  1085.  
  1086.         If you use multiple sets of hotspots for alternate graphics, you will
  1087.     probably want each set of hotspots to use the same links.  Normally in
  1088.     Orpheus it is not permitted to have more than one copy of a linkword; in
  1089.     other words, you can copy the text as often as you like, but only one
  1090.     instance of it can bear the embedded linking codes.  This rule is ignored
  1091.     for Graphic cards in order to allow multiple sets of hotspots to share
  1092.     links.  Note that to delete a linkword copy you must still use the
  1093.     Unlink command on the Link Menu; if a copy is detected, the unlinking
  1094.     procedure will only remove the linking codes from the linkword at the
  1095.     cursor, and will not affect the linked card.
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.                                       19
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  If()
  1145.  
  1146.         The if() command lets you test a condition, and either direct control
  1147.     to a specified label if the condition is true, or fall through to the
  1148.     next line if the condition is false.  If() commands must be followed on
  1149.     the same line by a goto with a label.
  1150.  
  1151.                 if (okay) goto ALRIGHT
  1152.  
  1153.     Only one parameter is permitted, from the following list:
  1154.  
  1155.                 okay
  1156.                 failed
  1157.                 mono
  1158.                 color
  1159.  
  1160.     "Okay" and "failed" test an internal flag that is set by the trymode()
  1161.     command (and in future by others).  "Mono" tests whether the user has a
  1162.     monochrome display running in mode 7.  (A monochrome display refers to one
  1163.     on which besides normal and blinking text we can use underline, bright,
  1164.     and reverse video, but not shades.)  "Color" tests whether the user has a
  1165.     true color display, as distinct from a 1-color display capable of showing
  1166.     16 shades.  Other tests will be added in future.
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.                                       20
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  Jump()
  1205.  
  1206.         The jump() command tells the Orpheus Reader to navigate directly to
  1207.     another card, which may be determined at random, by number, or by
  1208.     circumstance.  Jumping automatically terminates processing of the current
  1209.     script; in other words, you cannot jump to another card and then carry
  1210.     on to the next line of the script with the jump() command.  Jump commands
  1211.     cannot be simulated in OH.EXE.
  1212.  
  1213.         Up to two parameters are permitted, of which the first must be from
  1214.     the following list, while the second (if any) must be a card number as
  1215.     explained on the next page.
  1216.  
  1217.                 [card number]
  1218.                 home
  1219.                 random
  1220.                 retrace
  1221.  
  1222.     To force a jump to a particular card, navigate to that card in another
  1223.     window and open the File Menu.  To the right of the "Save As" command
  1224.     you will see the hilited number of that card.  Use this number as the
  1225.     jump parameter:
  1226.  
  1227.                 jump(112)       // if the card's number is 112
  1228.  
  1229.     Such a command could theoretically be given in any programmable card, but
  1230.     the logical place would be in an Action card, as a replacement for a
  1231.     Crosslink.  Whereas a Crosslink can have only one destination, an Action
  1232.     card can contain a script that tests various things and conditionally
  1233.     jumps to a choice of multiple destinations.  (In future releases the
  1234.     number of conditions to test will increase to give you considerable power
  1235.     and flexibility in this regard.)  Note that you should NEVER force a jump
  1236.     to either an Init or an Action card.
  1237.  
  1238.         To force a jump to Designated Home (or if none, the Homecard) use:
  1239.  
  1240.                 jump(home)
  1241.  
  1242.     Random jumps are permitted if you have previously initialized random
  1243.     jumps by using a jumplist() command together with the "random" parameter.
  1244.     To force a jump to a card selected at random, use:
  1245.  
  1246.                 jump(random)
  1247.  
  1248.     Finally, you can force a jump to the PREVIOUS card the reader visited:
  1249.  
  1250.                 jump(retrace)
  1251.  
  1252.     This last is probably the most useful variation of the jump() command.
  1253.     Suppose there are several cards with Crosslinks to the same card.  It
  1254.     would be impractical for that card to contain separate Crosslinks back
  1255.     to each one of them.  Although the user CAN retrace his path by clicking
  1256.  
  1257.  
  1258.  
  1259.                                       21
  1260.  
  1261.  
  1262.  
  1263.  
  1264.     on the Retrace symbol (or by pressing <Backspace> in the Reader or <Left
  1265.     Arrow> in OH.EXE), some users will not know this or will become frustrated
  1266.     by the need to think about whether they have or have not just come through
  1267.     a Crosslink.  The user-friendly solution is to give such a card an Action
  1268.     link using a phrase such as "Go Back" for the linkword; then use the
  1269.     command "jump(retrace)" in the Action card.
  1270.  
  1271.         The optional second parameter is the number of the card from which
  1272.     you wish to "pretend" to have jumped.  Suppose for example that you have
  1273.     a card that serves as a menu or table of contents, and that at the end
  1274.     of each branch leading down from it you have a "Return to Menu" or some
  1275.     such linkword, directing the reader back to the top.  Your jump() command
  1276.     might use "home" or the number of the menu card.  Now, if the reader were
  1277.     to return to the menu manually through a series of PgUp moves, on his
  1278.     arrival at the menu card the linkword through which he originally descended
  1279.     would be hilited, making it easy to select a different item from the menu.
  1280.     But by using the jump() command you skip over the intervening cards, so
  1281.     that Orpheus keeps hiliting the first linkword on the menu.  Here's where
  1282.     the second parameter comes in handy.  At each location where you wish to
  1283.     use jump(), go to the menu card (using a different Edit window) and find
  1284.     the linkword leading to that location.  Go through that linkword and open
  1285.     the File Menu to find the card's number, and use that as your second
  1286.     parameter.  The effect will be the same as if the reader had come from the
  1287.     card directly under the linkword instead of one far below.
  1288.  
  1289.                 jump(10, 12)
  1290.  
  1291.     This example jumps to card 10, and pretends to have done so from card 12.
  1292.     If card 10 has a linkword connected to card 12, that linkword will be
  1293.     hilited as if the reader had just come from there.
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.                                       22
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  Jumplist()
  1325.  
  1326.         The jumplist() command sets up a list of cards to which the Orpheus
  1327.     Reader can or cannot jump when given an appropriate jump() command as
  1328.     described in the previous section.  Currently such a list can only be
  1329.     set up for the purpose of making random jumps; a future release will add
  1330.     the ability to set up a list for a guided tour.
  1331.  
  1332.         Two parameters are required, of which the first must for now be the
  1333.     keyword "random".  The second parameter may be "all", or either "include"
  1334.     or "exclude" followed by a list of card numbers represented by their file
  1335.     extensions.  The example below initializes a random jumplist and tells
  1336.     the Orpheus Reader that choices may be made from all of the cards in the
  1337.     book.  Note that this automatically excludes Init and Action cards.
  1338.  
  1339.                 jumplist(random, all)
  1340.  
  1341.     The next example initializes a random jumplist that includes only the
  1342.     cards listed by number.  When the Reader encounters a jump(random)
  1343.     command, it will select at random from that list.  Note that the list must
  1344.     not include Init or Action cards.  (To find out the number of a particular
  1345.     card, open the File Menu while in that card and note the hilited number
  1346.     to the right of the "Save As" prompt.)
  1347.  
  1348.                 jumplist(random, include, 12, 43, 159,.........)
  1349.  
  1350.     The final example initializes a random jumplist that includes all cards
  1351.     EXCEPT those specified in the list.  When the Reader encounters a
  1352.     jump(random) command, it will select at random from all cards, rejecting
  1353.     any choice that is on the exclude list; it will also reject any choice
  1354.     that is an Init or Action card.
  1355.  
  1356.                 jumplist(random, exclude, 12, 76, 384,.........)
  1357.  
  1358.         The list of card numbers must be constructed as shown, with each
  1359.     number separated from the others by a comma; spaces are optional.
  1360.     If the list carries over to one or more additional lines, each broken line
  1361.     must end with a comma, and each additional line must begin with at least
  1362.     one leading space.  The list must be terminated by a closing parenthesis.
  1363.  
  1364.         The normal place to declare a jumplist is in an Init card.  You can
  1365.     build the list either manually or automatically.  Both procedures require
  1366.     you to start with the Init card with the uncompleted jumplist() command
  1367.     in one window, and then switch to another window to navigate to the
  1368.     various cards that you intend to add to the jumplist.  To do this
  1369.     manually, open the File Menu when in such a card, get the card number
  1370.     as shown to the right of the "Save As..." command, then switch to the
  1371.     window with your Init card and add the number to the list.
  1372.  
  1373.         The semi-automatic way to accomplish the same thing requires a couple
  1374.     of setup steps but is then much faster.  First, leave the Init card with
  1375.     the uncompleted jumplist() command in one window, making sure that the
  1376.  
  1377.  
  1378.  
  1379.                                       23
  1380.  
  1381.  
  1382.  
  1383.  
  1384.     cursor is at the end of the line and in the position where the next
  1385.     card number is to be inserted.  The example below shows this with an
  1386.     underscore representing the position of the cursor:
  1387.  
  1388.                 jumplist(random, include, _
  1389.  
  1390.     Open the Tools Menu and select "Jumplist", then select "List Window" and
  1391.     tell Orpheus which window contains the Init card with the jumplist.  Now
  1392.     switch to another window and navigate to whichever cards you wish to add
  1393.     to the list.  At each such card, press <Alt-F3>.  If the procedure is
  1394.     successful Orpheus will post a message saying "Added to list".  Let us
  1395.     suppose that the first card you add is numbered "15".  The example
  1396.     below shows the growing jumplist with the underscore representing the
  1397.     new position of the cursor, which Orpheus has advanced in preparation
  1398.     to receive the next number.  Of course you will only see this if you
  1399.     switch back to the window with the Init card.
  1400.  
  1401.                 jumplist(random, include, 15,_
  1402.  
  1403.     Remember that to terminate the list and make the command complete, you
  1404.     must remove the last comma if there is one, and add a closing parenthesis
  1405.     as in the final example.
  1406.  
  1407.                 jumplist(random, include, 15,17,23,32,58,2,76)
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.                                       24
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  Load()
  1445.  
  1446.         The load() command is intended for use with "external objects", such
  1447.     as uncompiled text files or other hypertext books.  It takes at least two
  1448.     parameters:  a keyword to define the kind of object you wish to load, and
  1449.     a filename.  Use the "new" keyword to change to a different compiled book;
  1450.     use "text" to load an external text file in the Reader's version of the
  1451.     FileView window.
  1452.  
  1453.     NEW
  1454.     Load(new, ...) provides a way of jumping to other hypertext books created
  1455.     with Orpheus.  To use it, open an Action link and give the load() command
  1456.     together with the "new" keyword and the name of the book to load:
  1457.  
  1458.                 load(new, filename.htx)
  1459.  
  1460.     The keyword "new" tells Orpheus that you want to load a new book.  For
  1461.     a well-behaved application you might want to ensure that the user actually
  1462.     has the desired book files.  You can do this with the lookfor() command,
  1463.     described below.  When a load() command is successful, it performs certain
  1464.     cleanup functions for whatever the user has just been reading, such as
  1465.     saving bookmarks and notes.  Then it fires up the new book, just as if the
  1466.     user had loaded it manually.  The transition is swift and seamless,
  1467.     especially if both books were designed by the same person in the same
  1468.     style.  Though currently an Orpheus book is limited to 32,000 links,
  1469.     with the load() command your work is infinitely extensible:  any book
  1470.     can contain links to hundreds or thousands of other books.
  1471.  
  1472.         Note that when load() is successful, the line with that command
  1473.     becomes in effect the last line of the script.  In other words, you
  1474.     cannot follow it with a play() command, for example, and expect music
  1475.     to play while the user starts reading the new book.
  1476.  
  1477.  
  1478.     TEXT
  1479.     Load(text, ...) tells the Orpheus Reader to load an external text file
  1480.     for viewing in the Reader's version of the FileView window.  To use it,
  1481.     open an Action link and give the load() command together with the "text"
  1482.     keyword and the name of the file to load.  As shown by the second example,
  1483.     the filespec can include a drive letter and path, but you should only
  1484.     do this if your work will remain on systems known to you.
  1485.  
  1486.                 load(text, filename.doc)
  1487.                 load(text, c:\biz\newinfo.txt)
  1488.  
  1489.     Load() has the additional capability of placing the reader at a specific
  1490.     line in a file.  The following command would load MANUAL.DOC with line
  1491.     235 at the top of the viewing window:
  1492.  
  1493.                 load(text, manual.doc, 235)
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.                                       25
  1500.  
  1501.  
  1502.  
  1503.  
  1504.     You can also specify a label instead of a number.  The next command would
  1505.     load the same file but with the line containing the label {New Listings}
  1506.     at the top of the window.  Note that in the script command the text of
  1507.     the label must be in quotation marks, while in the *file* it must be
  1508.     in curly braces, like so: {New Listings}.
  1509.  
  1510.                 load(text, manual.doc, "New Listings")
  1511.  
  1512.     FileView will not display the curly braces, and in fact the entire label
  1513.     can be hidden by placing it at the end of the line and inserting enough
  1514.     spaces to push it offscreen to the right.  (FileView does not wrap lines
  1515.     that are longer than the screen.)
  1516.  
  1517.         Why would you want to link to an uncompiled text file?  For books
  1518.     that will be distributed far and wide it might not make any sense, but in
  1519.     a business setting it can give your users convenient access to files that
  1520.     are frequently updated.  Users can edit such files themselves, using any
  1521.     editor or word processor capable of saving files as plain text.  They
  1522.     can even create additional links to their own files using the simple
  1523.     hypertext capabilities of FileView.  This feature is detailed in the
  1524.     online help of both OH.EXE and the Reader, but I'll repeat the essentials
  1525.     here.
  1526.  
  1527.         Provided the word "ORPHEUS" is found anywhere on the first line of a
  1528.     file, FileView will interpret certain characters in the file as being
  1529.     codes for embedded hypertext links.  These characters are:
  1530.     <angle brackets> around linkwords, [square brackets] around jump data,
  1531.     and {curly braces} around labels.  None of these characters will be
  1532.     displayed, nor will anything in square brackets.  The following examples
  1533.     show what you can do:
  1534.  
  1535.         <linkword>[#201]                 - jump to line 201
  1536.         <linkword>[:Hotels]              - jump to {Hotels} below
  1537.         <linkword>[:^Hotels]             - jump to {Hotels} ABOVE
  1538.         <linkword>[manual.doc]           - jump to MANUAL.DOC file
  1539.         <linkword>[manual.doc #201]      - jump to file, line 201
  1540.         <linkword>[manual.doc :Hotels]   - jump to file, line with {Hotels}
  1541.         {Hotels}                         - a label
  1542.  
  1543.     Note the difference between this syntax and the way things are done
  1544.     in the load() command.  I've given end-users a fairly compressed notation
  1545.     because it's easy to remember and is quick to type.
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.                                       26
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  Lookfor()
  1565.  
  1566.         The lookfor() command checks the user's disk for a file.  It takes
  1567.     a singe parameter, the file you wish to look for.  If the file is found
  1568.     the okay/failed flag is set to "okay"; if not it is set to "failed".
  1569.     The following example combines lookfor() with load() in a realistic
  1570.     setting:
  1571.  
  1572.                 lookfor(filename.htx)
  1573.                 if (failed) goto MESSAGE
  1574.                 load(new, filename.htx)
  1575.                 goto END
  1576.                 :MESSAGE
  1577.                 text(okay, "Unable to find FILENAME.HTX!")
  1578.                 :END
  1579.  
  1580.     This script checks for the presence of the desired book and skips to
  1581.     a text() command if the book cannot be found.  Otherwise it loads the
  1582.     book.  Even though a successful load() command would immediately
  1583.     abandon this script since it would no longer be present in memory,
  1584.     we insert a "goto END" line after it for logical consistency.
  1585.  
  1586.  
  1587.  Netwk()
  1588.  
  1589.         The netwk() command is for use with specially customized versions of
  1590.     the Orpheus Reader.  It takes an indeterminate number of parameters on
  1591.     a single line, which are passed as a sequence of null-terminated strings
  1592.     preceded by a 1-byte counter giving the number of strings in the sequence.
  1593.     Parameters are comma-delimited.
  1594.  
  1595.  
  1596.  
  1597.  
  1598.  
  1599.  
  1600.  
  1601.  
  1602.  
  1603.  
  1604.  
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.                                       27
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  Play()
  1625.  
  1626.         The play() command performs 1-voice music on the PC's internal
  1627.     speaker, temporarily suspending other processing until the music is
  1628.     finished.  There is 1 parameter, a music string composed of a sequence of
  1629.     letters and numbers according to the convention described below.  Letters
  1630.     in the music string must be capitalized as shown in the examples.  The
  1631.     music string may include spaces for readability.  A music string may carry
  1632.     over onto one or more additional lines, provided that each broken line
  1633.     ends with a comma and each additional line begins with one or more leading
  1634.     spaces.  The music string must be enclosed in quotation marks as if it
  1635.     were text.
  1636.  
  1637.  
  1638.     MUSIC SYNTAX
  1639.  
  1640.         A to G    Play the specified note in the current octave.
  1641.  
  1642.         #         Append to a note character (A to G) to make that
  1643.                     note sharp.
  1644.  
  1645.         .         Append to a note character or to a sharp (#) to
  1646.                     extend that note by half its length.  Multiple
  1647.                     dots can be used, and each extends the note by
  1648.                     half as much as the previous dot.
  1649.  
  1650.         Ln        Set the length of notes and pauses.  The value
  1651.                     of "n" is a number between 1 and 64, where 1
  1652.                     indicates a whole note, 2 a half note, 4 a quarter
  1653.                     note, and so on.  The default is L4.
  1654.  
  1655.         On        Set the octave for subsequent notes.  The value
  1656.                     of "n" may be a number from 0 to 6 to specify the
  1657.                     octave, or it can be a "+" or "-" character to
  1658.                     increment or decrement the current octave number.
  1659.                     The default is O4, which contains middle C.
  1660.  
  1661.         P         Pause (rest) for the duration specified by the
  1662.                     previous L command.
  1663.  
  1664.         Sn        Set the amount of silence between notes.  The
  1665.                     value of "n" is a number from 0 to 2.  If 0, each
  1666.                     note plays for the full period set by the previous
  1667.                     L command.  If 1, each note plays for 7/8 of that
  1668.                     period.  If 2, each note plays for 3/4 of that
  1669.                     period.  These effects correspond to legato,
  1670.                     normal, and staccato playing styles.  The default
  1671.                     is S1.
  1672.  
  1673.         Tn        Set the tempo of the music (the number of quarter
  1674.                     notes per minute).  The value of "n" is a number
  1675.                     from 32 to 255.  The default is T120.
  1676.  
  1677.  
  1678.  
  1679.                                       28
  1680.  
  1681.  
  1682.  
  1683.  
  1684.         Here are a few examples:
  1685.  
  1686.         /  "Mary Had a Little Lamb"
  1687.         play("T150 L8 EDCDEEE P DDD P EGG P EDCDEEE L16 P L8 EDDEDC")
  1688.  
  1689.         /  Beethoven's Fifth:
  1690.         play("T180 O2 L2 P L8 P GGG L2 D# L24 P L8 P FFF L2 D")
  1691.  
  1692.         /  Simple scale up and down:
  1693.         play("L4 C L8S2 DEFGAB S1L4 O+C O-L8S2 BAGFED L2 C")
  1694.  
  1695.         /  Chromatic scale over two octaves, with the string carried
  1696.         /  over onto a second line
  1697.         play("L16 CC#DD#EFF#GG#AA#B O+ CC#DD#EFF#GG#AA#B O+ L4 C P,
  1698.             L16 C O- BA#AG#GF#FED#DC#C O- BA#AG#GF#FED#DC# L4 C")
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738.  
  1739.                                       29
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  Quit()
  1745.  
  1746.         The quit() command tells the Orpheus Reader to exit, the same as if
  1747.     the user had pressed <Alt-X> except that no attempt is made to save
  1748.     configuration, bookmark, or notepad files.  There are no parameters.
  1749.  
  1750.         An obvious use for quit() would be to prevent access to a work in which
  1751.     high-quality graphics were REQUIRED, if the user's display was not capable
  1752.     of displaying those graphics.  For example, the following script would go
  1753.     into an Init off the Homecard; after checking to see whether the user has
  1754.     at least a VGA color display, it either flows through to the rest of the
  1755.     book or displays a message and exits the program.
  1756.  
  1757.                 trymode(18)
  1758.                 if (okay) goto HAS_VGA
  1759.                 :EXIT
  1760.                 text("This book requires a VGA color display")
  1761.                 quit()
  1762.                 :HAS_VGA
  1763.                 if (color) goto READY
  1764.                 goto EXIT
  1765.                 :READY
  1766.  
  1767.     Note how this script uses two different tests, either of which can
  1768.     branch to the exit sequence.  If the user does not have VGA, the script
  1769.     flows through to the quit() command and we exit the program; if the user
  1770.     has VGA but does not have color, the script backs up so that again we
  1771.     flow into the quit() command and exit.  The actual words used for the
  1772.     labels can be anything you like, and do not have to capitalized; I use
  1773.     uppercase labels for readability.
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.  
  1797.  
  1798.  
  1799.                                       30
  1800.  
  1801.  
  1802.  
  1803.  
  1804.  Run()
  1805.  
  1806.         The run() command launches an external program having an extension of
  1807.     either EXE or COM.  There is a single parameter consisting of a command
  1808.     line reproduced exactly as you would enter it at the DOS prompt.  The
  1809.     command line may include space-delimited parameters as you would enter
  1810.     them at the DOS prompt.  Since a ")" character is considered to terminate
  1811.     the command line, the latter may not include parentheses.  The run()
  1812.     command must not be used to launch batch files, nor can it be used to
  1813.     run an internal DOS command such as TYPE or COPY.  (See runbat() below.)
  1814.  
  1815.                 /  launch LIST.COM to display README
  1816.                 run(list readme)
  1817.                 /  launch GIFSHOW.EXE to display a sequence of 3 pictures
  1818.                 run(gifshow jupiter.gif saturn.gif neptune.gif)
  1819.                 /  launch EDIT.EXE with no file specified
  1820.                 run(edit)
  1821.  
  1822.  
  1823.  Runbat()
  1824.  
  1825.         The runbat() command launches a batch file or runs an internal DOS
  1826.     command such as TYPE or COPY.  (Internal DOS commands are those for which
  1827.     there is no separate program of the same name and with a COM or EXE
  1828.     extension.  External DOS commands are those which do refer to a separate
  1829.     program, such as MORE.EXE.)  There is a single parameter consisting of a
  1830.     command line reproduced exactly as you would enter it at the DOS prompt.
  1831.     Since a ")" character is considered to terminate the command line, the
  1832.     latter may not include parentheses.  If using runbat() to launch a batch
  1833.     file, the batch file may include calls to internal and external DOS
  1834.     commands as well as to other programs.  Runbat() can also launch programs
  1835.     having a COM or EXE extension, but it takes a little more memory than
  1836.     run(), so it is better to use run() for such programs.
  1837.  
  1838.                 /  launch ORDER.BAT and specify a certain order form
  1839.                 runbat(order book1.frm)
  1840.  
  1841.                 /  tell DOS to print REGISTER.DOC on the printer (1)
  1842.                 runbat(copy register.doc prn)
  1843.  
  1844.                 /  tell DOS to print REGISTER.DOC on the printer (2)
  1845.                 /  note that this version requires the ">" symbol
  1846.                 runbat(type register.doc >prn)
  1847.  
  1848.  
  1849.     Both run() and runbat() clear the screen to the normal DOS colors before
  1850.     carrying out the requested action.  What they do on return depends on
  1851.     whether they were called from an Action card or a Graphic card.  If called
  1852.     from a Graphic card, assuming that a graphic or ansi screen was displayed,
  1853.     both run() and runbat() attempt to restore whatever was onscreen before
  1854.     the external program was called.  In an Action card however this is not
  1855.     done; the screen is not restored until control returns to the parent card.
  1856.  
  1857.  
  1858.  
  1859.                                       31
  1860.  
  1861.  
  1862.  
  1863.  
  1864.  Set()
  1865.  
  1866.         The set() command enables you to assign a symbolic or numerical value
  1867.     to a variable.  Parameters consist of one or more "variable=value" phrases
  1868.     and may be as numerous as can fit on one line.  All variables have certain
  1869.     default values that are discussed below; once you have assigned a value
  1870.     to a variable it retains that value until you change it.  Currently only
  1871.     built-in variables may be set, but a future release will enable you to
  1872.     create variables of your own.  The following examples illustrate the use
  1873.     of the set() command:
  1874.  
  1875.                 set(blink=off)
  1876.                 set(draw=1, erase=14)
  1877.                 set(fadein=tunnelin, fadeout=venetian, delay=1)
  1878.  
  1879.     As you can see, some variables receive a numerical value, while others
  1880.     receive a symbolic value represented by a keyword.  The list below
  1881.     explains what the variables mean and what values they can receive.
  1882.  
  1883.     BLINK
  1884.     Blink refers to the appearance of high-intensity background colors
  1885.     when an ansi screen is displayed with the ansi() command.  Normally, such
  1886.     colors do NOT appear as high-intensity backgrounds but rather as areas
  1887.     that blink.  The ability to give the command "set(blink=off)" lets you
  1888.     work with a more exciting color palette in your ansi screens.  You can
  1889.     even use a time delay to show an ansi screen that starts off with blinking
  1890.     areas that suddenly stop and change color:
  1891.  
  1892.                 set(blink=on)      // in case it was set to off earlier
  1893.                 ansi(mypic.ans)    // display with blinking areas
  1894.                 waitfor(18)        // pause 1 second
  1895.                 set(blink=off)     // turn blink into bright backgrounds
  1896.                 ansi(mypic.ans)    // refresh display
  1897.                 waitfor()          // wait for keypress
  1898.  
  1899.     Note that for this effect to work you MUST make the second ansi() call,
  1900.     because Orpheus does not actually change blink when you give the set()
  1901.     command, only when an ansi screen is displayed.
  1902.  
  1903.     DELAY
  1904.     Delay refers to the speed of certain special effects such as fadein and
  1905.     fadeout, discussed below.  The default value of delay is always 0, which
  1906.     results in a reasonably fast effect.  Some special effects are quicker
  1907.     than others, and some are more attractive than others when slowed down.
  1908.     Since the delay setting applies to BOTH fadein and fadeout (and later
  1909.     perhaps to other variables) you may have to change it repeatedly if you
  1910.     are combining special effects in a sequence.  The first example below
  1911.     sets delay to a very slow setting; the second returns it to normal:
  1912.  
  1913.                 set(delay=4)
  1914.                 / .........
  1915.                 set(delay=0)
  1916.  
  1917.  
  1918.  
  1919.                                       32
  1920.  
  1921.  
  1922.  
  1923.  
  1924.     DRAW, ERASE
  1925.     Draw and erase have to do with making hotspots in OH.EXE.  They receive
  1926.     numerical values from 0 to 15, representing color values from black to
  1927.     white as shown in the chart below.  Their default values are draw=15
  1928.     (white), erase=0 (black).  The following example sets draw to yellow,
  1929.     erase to grey:
  1930.  
  1931.                 set(draw=14, erase=7)
  1932.  
  1933.     You only need to change these variables if the colors of a particular
  1934.     graphic made it difficult for you to distinguish between a hotspot in
  1935.     progress and the original graphic.  Finished hotspots do not in any way
  1936.     alter the appearance of a graphic, and references to these variables are
  1937.     not included in the compiled version of a book.
  1938.  
  1939.  
  1940.                     0 black             8 dark grey
  1941.                     1 blue              9 light blue
  1942.                     2 green            10 light green
  1943.                     3 cyan             11 light cyan
  1944.                     4 red              12 light red
  1945.                     5 magenta          13 light magenta
  1946.                     6 brown            14 yellow
  1947.                     7 grey             15 white
  1948.  
  1949.  
  1950.     FADEIN, FADEOUT
  1951.     Fadein and fadeout refer to the style with which a graphic is displayed
  1952.     or erased.  The following styles are available:
  1953.  
  1954.                 normal ........ the default:  replace pixels at random
  1955.                 diagonal ...... splits the screen diagonally
  1956.                 wipe .......... wipes image on or off from left to right
  1957.                 split ......... splits the screen horizontally
  1958.                 unveil ........ like a curtain
  1959.                 venetian ...... like venetian blinds
  1960.                 tunnelin ...... tunnels from outside to center
  1961.                 tunnelout ..... tunnels from center to outside
  1962.                 check ......... checkerboard style
  1963.                 off ........... ** turn off fades for multiple graphics **
  1964.  
  1965.     Fadein and fadeout are set individually, so you can have your graphics
  1966.     fading in with one style and fading out with another; you can even have a
  1967.     sequence of graphics in which the fade styles change with each graphic.
  1968.     To make this work, bear in mind that a graphic does not fade out until it
  1969.     is about to be replaced -- whether by another graphic, by an ansi screen,
  1970.     or by a text card.  The following sequence varies both the speed and the
  1971.     style of fades:
  1972.  
  1973.                 set(fadein=tunnelin, fadeout=tunnelout, delay=1)
  1974.                 graphic(example1.pcx, 13, full)
  1975.                 waitfor()
  1976.  
  1977.  
  1978.  
  1979.                                       33
  1980.  
  1981.  
  1982.  
  1983.  
  1984.                 set(fadein=diagonal, delay=0)
  1985.                 graphic(example2.pcx, 13, full)
  1986.                 waitfor()
  1987.                 set(fadein=wipe, fadeout=split)
  1988.                 graphic(example3.pcx, 13, full)
  1989.                 set(fadeout=venetian, delay=3)
  1990.                 waitfor()
  1991.  
  1992.     The sequence begins by setting fadein, fadeout and delay for the first
  1993.     graphic.  Before moving on it changes the fadein style for the second
  1994.     graphic.  After displaying the second graphic it changes the fadeout style
  1995.     for it as well as the fadein style for the third graphic.  After that
  1996.     graphic is displayed the fadeout style is changed again, and the delay
  1997.     factor set slow to emphasize the quality of the chosen style.  Note that
  1998.     each graphic is separated by a waitfor() command to ensure that each one
  1999.     stays onscreen until the user presses a key.  (The last waitfor() command
  2000.     would only be necessary in an Init or Action card.)
  2001.  
  2002.         In the final example we turn fades OFF in order to allow multiple
  2003.     graphics onscreen at the same time:
  2004.  
  2005.             set(fadein = off, fadeout = off)
  2006.             graphic(first.pcx, 18, 0, 0)
  2007.             graphic(second.pcx, 18, 450, 0)
  2008.             graphic(third.pcx, 18, 0, 390)
  2009.             graphic(fourth.pcx, 18, 450, 390)
  2010.             set(fadeout = normal)
  2011.  
  2012.  
  2013.     MODE
  2014.     Mode enables you to set the video mode independently of a call to
  2015.     graphic().  It is intended for situations in which you wish to do
  2016.     something that requires the prior establishment of a graphical video
  2017.     mode.  Specifically, the gbox() and gtext() commands do not include a
  2018.     mode parameter, and so require that the video mode be changed before
  2019.     they are called.  In the following example we want to draw a white box
  2020.     in the middle of the screen and then overlay a graphic inside it:
  2021.  
  2022.             set(fadein = off, fadeout = off, mode = 13)
  2023.             gbox(15, 99, 49, 120, 100)
  2024.             graphic(portrait.pcx, 13, 107, 55)
  2025.             set(fadeout = normal)
  2026.  
  2027.     Turning off fades ensures that the graphic() call will not erase the
  2028.     screen before displaying portrait.pcx.  Since the box is drawn larger
  2029.     than the graphic, which in turn is positioned so that its upper left
  2030.     corner is below and to the right of the upper left corner of the box,
  2031.     the final effect is of a white frame around the graphic.  However, in
  2032.     order to do this we had to set the video mode first, since gbox() requires
  2033.     that a graphical video mode be in effect before it is called.  Another way
  2034.     to achieve the same effect would be to make the graphic() call first,
  2035.     then draw the frame around it with four separate calls to gbox().
  2036.  
  2037.  
  2038.  
  2039.                                       34
  2040.  
  2041.  
  2042.  
  2043.  
  2044.  Text()
  2045.  
  2046.         For use in Action cards, the text() command lets you display up to
  2047.     23 lines of text in a temporary window, with optional parameters to
  2048.     control appearance, screen position, and the length of time that the
  2049.     window remains onscreen.  If options are not specified, Orpheus uses
  2050.     default behaviors such as calculating screen coordinates to center the
  2051.     window.  The window area is automatically sized to fit the longest line,
  2052.     except when the "okay" keyword is used:  this forces the window to
  2053.     become a standard "Okay" box with the limitations discussed below.
  2054.  
  2055.         The text() command is at once powerful, flexible, and easy to use.
  2056.     It is ideal for situations where you want to display a small amount of
  2057.     information that does not require a separate card (such as the definition
  2058.     of a word), or where you want the temporary text to be shown side-by-side
  2059.     with text on the parent card.
  2060.  
  2061.     LINES OF TEXT
  2062.     The text() command must receive at least one string parameter, meaning
  2063.     a line of text enclosed in quotation marks.  Anything enclosed in
  2064.     quotation marks is interpreted as one line of text.
  2065.  
  2066.                 text("This is a one-line message")
  2067.  
  2068.     This command displays the quoted text in a standard box, centered on
  2069.     the screen.  To display multiple lines of text, separate your parameters
  2070.     with commas as you would with other commands.  If there is not enough
  2071.     room on a line, or if you wish to enter a multiline command so that it
  2072.     will resemble what you intend to display, start each new parameter on
  2073.     a separate line, being sure to indent each such additional line by at
  2074.     least one leading space.  The following examples have exactly the same
  2075.     results:
  2076.  
  2077.                 text("This message", "will appear", "on three lines.")
  2078.  
  2079.                 text("This message",
  2080.                      "will appear",
  2081.                      "on three lines.")
  2082.  
  2083.     In both versions, each intended line of text is enclosed in quotation
  2084.     marks, with commas separating the parameters.  In the second version the
  2085.     two additional lines are indented so as to ensure that Orpheus doesn't
  2086.     misinterpret them later as separate commands.  Regardless of whether
  2087.     the lines are entered as shown in the first version or in the second,
  2088.     the result will show all three lines flush left in a centered box,
  2089.     with two spaces on either side of the longest line:
  2090.  
  2091.                              +===================+
  2092.                              |  This message     |
  2093.                              |  will appear      |
  2094.                              |  on three lines.  |
  2095.                              +===================+
  2096.  
  2097.  
  2098.  
  2099.                                       35
  2100.  
  2101.  
  2102.  
  2103.  
  2104.     Individual text strings cannot be broken by a newline; in other words,
  2105.     you CANNOT do this:
  2106.  
  2107.                 text("This broken line will
  2108.                       generate an error message")
  2109.  
  2110.     To include a blank line in your text, enter the blank line as a space
  2111.     enclosed in quotation marks, like so:
  2112.  
  2113.                 text("This message", "will appear", " ", "on four lines!")
  2114.  
  2115.                              +===================+
  2116.                              |  This message    |
  2117.                              |  will appear     |
  2118.                              |                  |
  2119.                              |  on four lines!  |
  2120.                              +===================+
  2121.  
  2122.     SPECIAL CHARACTERS
  2123.     Two characters must be given special handling if you wish to include
  2124.     them in your lines of text.  The  "  character normally means the
  2125.     beginning or end of a text; to include it as a literal character, precede
  2126.     it with a  \  backslash.  The backslash in turn normally means that the
  2127.     next character is special, so to include it as a literal character,
  2128.     precede it by another backslash.  For example:
  2129.  
  2130.                 text("This \"message\"",
  2131.                      "gives the path",
  2132.                      "to C:\\ORPHEUS")
  2133.  
  2134.                              +===================+
  2135.                              |  This "message"  |
  2136.                              |  gives the path  |
  2137.                              |  to C:\ORPHEUS.  |
  2138.                              +===================+
  2139.  
  2140.  
  2141.     COORDINATES
  2142.     You can position the text window by specifying the screen coordinates of
  2143.     the upper left corner of the box.  Row 1 is at the top of the screen and
  2144.     column 1 is at the far left.  If two numbers are entered, the first is
  2145.     the row, the second is the column.  If only one number is entered it
  2146.     represents the row; the box will be horizontally centered.  You cannot
  2147.     specify the column without giving a number for the row.  If no numbers are
  2148.     given the window is centered vertically and horizontally.  For example:
  2149.  
  2150.                 text(1, "This will be centered at the top of the screen.")
  2151.  
  2152.                 text(1, 1, "This will be at the upper left corner.")
  2153.  
  2154.                 text("This will be centered vertically and horizontally.")
  2155.  
  2156.  
  2157.  
  2158.  
  2159.                                       36
  2160.  
  2161.  
  2162.  
  2163.  
  2164.                 text(18, 40, "This will appear", "in the lower right.")
  2165.  
  2166.     Whenever you use text() with coordinates, use the <Alt-G> command to
  2167.     verify your parameters and see the results.  (Place the cursor on the
  2168.     line where the command begins, then press <Alt-G>.)  If a row or column
  2169.     parameter would result in the window being partially offscreen, Orpheus
  2170.     will give an error message (and will not compile the command).
  2171.  
  2172.     COLOR
  2173.     The default colors of the text() window are those of the standard "Okay"
  2174.     box.  You have two other choices:  by using the "color" keyword with
  2175.     either the "help" or "text" keywords, you can use the current colors of
  2176.     the Help dialog or simply the current text color.  The real colors shown
  2177.     will depend on the current settings when the user views your book.
  2178.  
  2179.                 text("This appears in the colors of the \"Okay\" box")
  2180.  
  2181.                 text(color = help, "This will look like the Help window")
  2182.  
  2183.                 text(color = text, "This will look like normal text")
  2184.  
  2185.     Notice that the word "text" operates both as a command and as a keyword.
  2186.     When you use text color, both the border and the text itself appear in
  2187.     the same color.  With the other settings, the border is usually a
  2188.     different color.
  2189.  
  2190.     FRAME
  2191.     The default frame style of the window border is a double-line box.  You
  2192.     set your own style by using the "frame" keyword with a number from 0 to 6.
  2193.     The numbers represent the styles presented in the Frame Dialog, which
  2194.     you can view by opening the Project Menu and selecting "Frame".
  2195.  
  2196.                 text(frame = 1, "This appears in a single-line box")
  2197.  
  2198.                 text(frame = 0, "This appears in a box with no frame")
  2199.  
  2200.                 text(frame = 5, "This appears in a box with single lines",
  2201.                                 "on the top and sides, and a double line",
  2202.                                 "on the bottom")
  2203.  
  2204.  
  2205.     TIMING
  2206.     The default behavior of a text window is to remain onscreen until the
  2207.     user presses a key or clicks the mouse.  By using the "delay" keyword
  2208.     with a number from 1 to 99, you can specify the number of seconds for
  2209.     Orpheus to wait before clearing the screen automatically.  If the user
  2210.     presses a key before the time is up, Orpheus stops waiting.  (Note that
  2211.     setting "delay" inside a text() command does NOT affect the delay
  2212.     setting for fade effects in graphic modes.)
  2213.  
  2214.                 text("This remains until the user presses a key")
  2215.  
  2216.                 text(delay = 5, "This remains for 5 seconds only")
  2217.  
  2218.  
  2219.  
  2220.  
  2221.                                       37
  2222.  
  2223.  
  2224.  
  2225.  
  2226.     Now let's see all of the text() parameters working together:
  2227.  
  2228.                 text(1, 50, color = help, frame = 6, delay = 30,
  2229.                     "This little message",
  2230.                     "stretches from the",
  2231.                     "top line down",
  2232.                     "along the right half",
  2233.                     "of the screen, and",
  2234.                     "has the colors of the",
  2235.                     "Help dialog.",
  2236.                     " ",
  2237.                     "It has 2 blank lines,",
  2238.                     "2 \"quotation\" marks,",
  2239.                     "and a \\backslash,",
  2240.                     "not to mention,",
  2241.                     "commas at the ends",
  2242.                     "of several lines.",
  2243.                     " ",
  2244.                     "The frame has single",
  2245.                     "lines at top and left,",
  2246.                     "double lines at bottom",
  2247.                     "and right.  After 30",
  2248.                     "seconds it disappears")
  2249.  
  2250.  
  2251.     THE "OKAY" KEYWORD
  2252.     If you use the "okay" keyword as the first parameter in a text()
  2253.     command, you are telling Orpheus to display your message in a standard
  2254.     Okay box.  This means that the dimensions, position, color, and frame
  2255.     of the window are determined entirely by Orpheus, but the resulting
  2256.     window has a hilited "Okay" prompt in the lower right window.  No delay
  2257.     is permitted:  the user must press a key or click a mouse button.
  2258.     Your message is limited to 7 lines, with a maximum line length of 57
  2259.     characters.  (The longest line is centered in the window, with any other
  2260.     lines displayed flush left with it.)
  2261.  
  2262.  
  2263.         +=============================================================+
  2264.         |                                                             |
  2265.         |         This book requires an EGA graphics display.         |
  2266.         |         Sorry about that!
  2267.         |                                                  < Okay >   |
  2268.         +=============================================================+
  2269.  
  2270.  
  2271.  
  2272.  
  2273.  
  2274.  
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280.  
  2281.                                       38
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  Trymode()
  2287.  
  2288.         The trymode() command provides a simple and precise way to determine
  2289.     the capabilities of the user's video hardware.  The single parameter is
  2290.     the number of a video mode.  Trymode() does not actually set the video
  2291.     mode, but rather tests the user's video system to see if it is capable
  2292.     of switching to that mode, and sets an internal flag accordingly.  If
  2293.     the display CAN switch to that mode the flag is set to "okay".  If the
  2294.     display CANNOT switch to that mode the flag is set to "failed".
  2295.  
  2296.                 trymode(16)                 // can we do EGA?
  2297.                 if (failed) goto END
  2298.                 graphic(ega_pic.pcx, 16, full)
  2299.                 :END
  2300.  
  2301.         Use trymode() in terms of the particular graphics you wish to display.
  2302.     The example above shows a script that might go in a Graphic card.
  2303.     Presumably the author first wrote the graphic() command and experimented
  2304.     with the mode parameter until he was sure that mode 16 was needed.  As
  2305.     shown by Table 1, "Modes and Resolutions" (at the end of this guide), mode
  2306.     16 can be handled by EGA/VGA displays, but not by less advanced displays
  2307.     such as the CGA. By controlling the program flow depending on the results
  2308.     of the trymode() test, he can ensure that if the user's hardware cannot
  2309.     display the graphic nothing bad will happen:  the script will harmlessly
  2310.     skip to the end.
  2311.  
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.  
  2319.  
  2320.  
  2321.  
  2322.  
  2323.  
  2324.  
  2325.  
  2326.  
  2327.  
  2328.  
  2329.  
  2330.  
  2331.  
  2332.  
  2333.  
  2334.  
  2335.  
  2336.  
  2337.  
  2338.  
  2339.  
  2340.  
  2341.                                       39
  2342.  
  2343.  
  2344.  
  2345.  
  2346.  Waitfor()
  2347.  
  2348.         The waitfor() command enables you to insert a pause in a script.
  2349.     The optional parameter is a number representing 18ths of a second.  If
  2350.     there is no parameter Orpheus waits until the user presses a key.  If
  2351.     a number is given Orpheus waits that number of 18ths of a second OR until
  2352.     the user presses a key.  In other words, waitfor() gives you an optionally
  2353.     timed pause that can always be broken by a keypress.
  2354.  
  2355.                 /  wait indefinitely until keypress
  2356.                 waitfor()
  2357.                 /  wait 1 second (or until keypress)
  2358.                 waitfor(18)
  2359.                 /  wait 10 seconds (or until keypress)
  2360.                 waitfor(180)
  2361.  
  2362.         If you display graphics or ansi files from Init or Action cards, you
  2363.     will soon notice that you MUST place a waitfor() command at the end of
  2364.     the script.  Otherwise, control returns immediately to the parent card
  2365.     and the image disappears a fraction of a second after it was displayed.
  2366.     This is NOT the case with Graphic cards, where control remains with the
  2367.     last-displayed image in the same manner as with a text card.
  2368.  
  2369.  
  2370.  
  2371.  
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.  
  2384.  
  2385.  
  2386.  
  2387.  
  2388.  
  2389.  
  2390.  
  2391.  
  2392.  
  2393.  
  2394.  
  2395.  
  2396.  
  2397.  
  2398.  
  2399.  
  2400.  
  2401.                                       40
  2402.  
  2403.  
  2404.  
  2405.  
  2406.   ---------------------------------------------------------------------------
  2407.                      CHAPTER 3  -  CONVERTING OLD COMMANDS
  2408.   ---------------------------------------------------------------------------
  2409.  
  2410.  
  2411.  
  2412.  Versions Before 1.30:  Graphic Commands
  2413.                         Run Commands
  2414.                         Random Commands
  2415.  Versions Before 1.50:  Hotspot()
  2416.                         Jump(), Jumplist()
  2417.                         Play()
  2418.  
  2419.  
  2420.         ALL programming commands from versions prior to 1.30 must be
  2421.     converted to the new standard, which is described in Chapter 1 and in the 
  2422.     Command Reference (Chapter 2).  Commands no longer have to be entered in 
  2423.     capital letters.  Most conversions concern commands that would have been 
  2424.     in Graphic cards.  In addition, users of versions 1.30 to 1.41 will need 
  2425.     to update their use of hotspot(), jump(), jumplist(), and play().
  2426.  
  2427.  
  2428.  Graphic Commands - Before 1.30
  2429.  
  2430.         The commands FILEPATH=, RESOLUTION=, and MODE= are now combined into
  2431.     the graphic() command.  The following data in the old version:
  2432.  
  2433.                 FILEPATH=c:\art\bkcover.pcx
  2434.                 RESOLUTION=640x200
  2435.                 MODE=14
  2436.  
  2437.     becomes this in the new version:
  2438.  
  2439.                 graphic(bkcover.pcx, 14, full)
  2440.  
  2441.     There are three points to notice here.  (1) Instead of specifying the
  2442.     complete filepath you should give only the filename.  Although you _can_
  2443.     give a complete filepath, this would be compiled into the finished version
  2444.     of your work and would be of no use to your readers.
  2445.  
  2446.     (2) Instead of telling Orpheus what resolution to use, with the video mode 
  2447.     being an optional detail, you now specify only the video mode.  The table 
  2448.     of Modes & Resolutions makes it easy to find an appropriate mode, and you 
  2449.     can test the results by placing the cursor on the line with the command 
  2450.     and pressing <Alt-G>. 
  2451.  
  2452.     (3) Until Version 1.30 you could ONLY display full-screen graphics.  Now
  2453.     you can display graphics that are smaller than the screen and place them
  2454.     anywhere you want using parameters 3 to 5.  To display a full-screen
  2455.     graphic, just use the word "full" as in the example above.  Read the entry
  2456.     on graphic() in Chapter 2 to learn about displaying smaller graphics.
  2457.  
  2458.  
  2459.  
  2460.  
  2461.                                       41
  2462.  
  2463.  
  2464.  
  2465.  
  2466.         The commands HOTSPOT= and LINKWORD= are now combined into the
  2467.     hotspot() command.  This command takes the linkword as the first
  2468.     parameter, with the hotspot data string as the second parameter.  Note
  2469.     that when you draw a hotspot on a graphic, Orpheus enters the hotspot()
  2470.     command for you automatically along with the hotspot data, the same as it
  2471.     did in previous versions.  If you have existing hotspots you must delete
  2472.     redraw them, but read the following if you also have associated linkwords
  2473.     that you wish to keep.
  2474.  
  2475.         Suppose you have a graphic of a Mississippi riverboat, showing a
  2476.     gambler on whom you've made a hotspot.  In the old commands you would
  2477.     have something like:
  2478.  
  2479.             HOTSPOT=5Q&6Q(7P*8P+9P+9[":O/;O0<N2=N2>U,?U#?Y(@[&■
  2480.             LINKWORD=gambler
  2481.  
  2482.     In the new version this must become:
  2483.  
  2484.             hotspot( gambler, "0..........data string.........")
  2485.  
  2486.     Before you can redraw the hotspot you will have to comment out any lines 
  2487.     containing commands that are no longer valid.  Get your graphic() command 
  2488.     working first (you can test it individually with <Alt-G>), then comment 
  2489.     out all other lines by inserting a "/" at the far left.  Now delete the
  2490.     "HOTSPOT" line entirely, leaving the cursor on that empty line.  You can
  2491.     now press <Alt-C> and, if the graphic displays correctly, follow the
  2492.     procedure for making a hotspot described in Chapter 2.  Upon return from
  2493.     the graphic you will see a line like the one above, but with the word
  2494.     "linkword" as the first parameter.  The final step is delete that word,
  2495.     then mark the original linkword you wish to replace it with and MOVE it
  2496.     into the new location.  You can then remove the "LINKWORD" line.
  2497.  
  2498.         NOTE:  previous versions of Orpheus simply ignored hotspot commands
  2499.     for which the linkword command did not actually have a linkword with a
  2500.     completed link on it.  As of Version 1.30, Orpheus considers this an
  2501.     incomplete command and will not let you use the Alt-C command to perform
  2502.     the script and create new hotspots.  To bypass this without deleting
  2503.     the command, comment it out by placing a ";" or "/" at the beginning of
  2504.     the line.
  2505.  
  2506.         Finally, the DRAW= and ERASE= commands (for adjusting the colors used
  2507.     while drawing hotspots) have been changed into optional parameters of
  2508.     the new set() command.  Thus, if you used the following before:
  2509.  
  2510.             DRAW=14         // draw in yellow
  2511.             ERASE=1         // erase in blue
  2512.  
  2513.     you would now use the following:
  2514.  
  2515.             set(draw=14, erase=1)
  2516.  
  2517.  
  2518.  
  2519.  
  2520.  
  2521.                                       42
  2522.  
  2523.  
  2524.  
  2525.  
  2526.  Run Commands - Before 1.30
  2527.  
  2528.         The RUN= and RUNBAT= commands now use parentheses in place of the "="
  2529.     sign.  If you have a line like:
  2530.  
  2531.             RUN=print file.doc
  2532.  
  2533.     you would convert it to:
  2534.  
  2535.             run(print file.doc)
  2536.  
  2537.  
  2538.  Random Commands - Before 1.30
  2539.  
  2540.         The RANDOM= commands have been replaced by the more capable jump()
  2541.     and jumplist() commands.  When specific cards were listed we originally
  2542.     used the 3-letter extension from the filename; as of 1.50 we get the
  2543.     card number in decimal form by opening the File Menu while in that card,
  2544.     and looking at the "Save As" line.  The card number is hilited at the 
  2545.     right.
  2546.  
  2547.             RANDOM=ALL                            // becomes:
  2548.             jumplist(random, all)
  2549.  
  2550.             RANDOM=INCLUDE,00B,01A,...            // became until 1.50,
  2551.             jumplist(random, include=00B,01A,...) // but is now:
  2552.             jumplist(random, include, 12, 49, ...)
  2553.  
  2554.             RANDOM=EXCLUDE,02Z,03G,...            // became until 1.50,
  2555.             jumplist(random, exclude=02Z,03G,...) // but is now:
  2556.             jumplist(random, exclude, 72, 99,...)
  2557.  
  2558.             RANDOM=JUMP                     becomes:
  2559.             jump(random)
  2560.  
  2561.     The jump() command in particular has far more useful purposes than the
  2562.     above, as you can see in the discussion of it in Chapter 2, the
  2563.     Programming Command Reference.
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.  
  2580.  
  2581.                                       43
  2582.  
  2583.  
  2584.  
  2585.  
  2586.  Hotspot() - Before 1.50
  2587.  
  2588.         As noted above, from versions 1.30 to 1.41 the hotspot() command
  2589.     took a data string enclosed in two copies of the block character, ascii
  2590.     254.  As of version 1.50 the data string is enclosed in quotation marks
  2591.     like an ordinary text string, but has some other differences that are
  2592.     equally important.  First, the first character of the string is now either 
  2593.     "0" or "1" to mark a hotspot created for either a true graphic or an ansi 
  2594.     screen respectively.  Second, the characters used in the string are drawn
  2595.     from a higher range of ascii values, making old data strings completely
  2596.     incompatible with version 1.50 and up.  (The new standard is both more
  2597.     coherent and more powerful, so this should be the last time you have to
  2598.     convert your hotspots.)
  2599.  
  2600.         To convert existing hotspot commands, you will have to redraw them
  2601.     and let Orpheus insert the new data string.  Assuming you have a command
  2602.     a completed linkword that you wish to keep, comment out that line and
  2603.     any others that are no longer valid, then insert a blank line or two
  2604.     and proceed as described in chapter 2 for making a hotspot.  You should
  2605.     be able to redraw your hotspot without any difficulty.  Upon return from
  2606.     the graphic, delete the dummy word "linkword" and replace it with what
  2607.     you really want by marking the original linkword and moving it into place.
  2608.  
  2609.  
  2610.  Jump(), Jumplist() - Before 1.50
  2611.  
  2612.         When specific cards were referred to, these commands previously
  2613.     used the 3-letter extension from each card's filename.  In the case of
  2614.     jump() a colon was used to precede the 3-letter extension.  The new
  2615.     standard makes things simpler by using numbers in decimal, without some
  2616.     of the trappings that used to be required.  To find the number of a
  2617.     card, navigate to that card and open the File Menu; the number will be
  2618.     hilited on the "Save As" line.
  2619.  
  2620.             OLD USAGE:
  2621.             jumplist(random, include=00A, 01B, 0G9........)
  2622.             jump(:00A)
  2623.  
  2624.             NEW USAGE:
  2625.             jumplist(random, include, 10, 42, 129..........)
  2626.             jump(10)
  2627.  
  2628.     As you can see, the new standard is simpler and more in tune with the
  2629.     way other commands are given.
  2630.  
  2631.  
  2632.  Play() - Before 1.50
  2633.  
  2634.         The music string given in a play() command must now be enclosed in
  2635.     quotation marks, as shown in Chapter 2.
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.                                       44
  2642.  
  2643.  
  2644.  
  2645.  
  2646.   ---------------------------------------------------------------------------
  2647.                        TABLE 1  -  MODES AND RESOLUTIONS
  2648.   ---------------------------------------------------------------------------
  2649.  
  2650.  
  2651.  
  2652.         All of the listed video modes are graphic modes.  The "Resolution"
  2653.     column gives the number of pixels onscreen, with the first number being
  2654.     the horizontal count (pixel columns), the second being the vertical count
  2655.     (pixel rows).  The "Text" column refers to the number of character cells
  2656.     available when text is displayed using the built-in ROM characters (as
  2657.     seen in text mode).  The numbers are again given as columns x rows.
  2658.  
  2659.         Where two numbers are given under "Colors", such as 16/64, the first
  2660.     figure represents the number of colors that can be displayed at one time,
  2661.     while the second figure represents the number of colors available to
  2662.     choose from in that video mode.  256K means 262,144 possible colors.
  2663.  
  2664.  
  2665.             Mode   Resolution  Text     Colors      Adapters
  2666.  
  2667.             4      320x200     40x25       4        CGA/EGA/VGA/MCGA
  2668.             5      320x200     40x25       4        CGA/EGA/VGA/MCGA
  2669.             6      640x200     80x25      2/16      CGA/EGA/VGA/MCGA
  2670.             9      320x200     40x25      16        Tandy,PCjr
  2671.            12      320x200     40x25       2        HGC
  2672.            13      320x200     40x25      16        EGA/VGA
  2673.            14      640x200     80x25      16        EGA/VGA
  2674.            15      640x350     80x25       2        EGA/VGA
  2675.            16      640x350     80x25     16/64      EGA/VGA
  2676.            17      640x480     80x30      2/256K    VGA/MCGA
  2677.            18      640x480     80x30     16/256K    VGA
  2678.            19      320x200     40x25    256/256K    VGA/MCGA
  2679.            20      320x200     40x25    256/256K    VGA
  2680.            21      320x400     40x50    256/256K    VGA
  2681.            22      320x240     40x30    256/256K    VGA
  2682.            23      320x480     40x60    256/256K    VGA
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.                                       45
  2702.  
  2703.